Skip Headers

Oracle® Call Interface Programmer's Guide, 10g Release 2 (10.2) Part Number B14250-02 |
Home | Book List | Contents | Index | Master Index | Feedback

Previous | Next
| View PDF

# OCI Miscellaneous Object Functions

This section describes the miscellaneous object functions.

Table 17-9 Miscellaneous Object functions

Function/Page | Purpose
--- | ---
OCIObjectCopy() | Copy one instance to another
OCIObjectGetAttr() | Gets an object attribute
OCIObjectGetInd() | Get `NULL` structure of an instance
OCIObjectGetObjectRef() | Return reference to a given object
OCIObjectGetTypeRef() | Get a reference to a TDO of an instance
OCIObjectLock() | Lock a persistent object
OCIObjectLockNoWait() | Lock a persistent object but do not wait for the lock
OCIObjectPin() | Create a new instance
OCIObjectSetAttr() | Sets an object attribute

## OCIObjectCopy()

Purpose

Copies a source instance to a destination.

Syntax

    sword OCIObjectCopy ( OCIEnv              *env,
                          OCIError            *err,
                          CONST OCISvcCtx     *svc,
                          dvoid               *source,
                          dvoid               *null_source,
                          dvoid               *target,
                          dvoid               *null_target,
                          OCIType             *tdo,
                          OCIDuration         duration,
                          ub1                 option );

Parameters

env (IN/OUT)

  The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.

err (IN/OUT)

  The OCI error handle. If there is an error, it is recorded in `err` and this function returns `OCI_ERROR`. Obtain diagnostic information by calling `OCIErrorGet()`.

svc (IN)

  An OCI service context handle, specifying the service context on which the copy operation is taking place

source (IN)

  A pointer to the source instance; if it is an object, it must be pinned.

  See Also: "OCIObjectPin()"

null_source (IN)

  Pointer to the `NULL` structure of the source object.

target (IN)

  A pointer to the target instance; if it is an object is must be pinned.

null_target (IN)

  A pointer to the `NULL` structure of the target object.

tdo (IN)

  The TDO for both the source and the target. Can be retrieved with `OCIDescribeAny()`.

duration (IN)

  Allocation duration of the target memory.

option (IN)

  This parameter is currently unused. Pass as zero or `OCI_DEFAULT`.

Comments

This function copies the contents of the `source` instance to the `target` instance. This function performs a deep-copy such that all of the following is copied:

- all the top level attributes (see the exceptions later)

- all secondary memory (of the source) reachable from the top level attributes

- the `NULL` structure of the instance

Memory is allocated with the duration specified in the `duration` parameter.

Certain data items are not copied:

- If the option `OCI_OBJECTCOPY_NOREF` is specified in the `option` parameter, then all references in the source are not copied. Instead, the references in the target are set to `NULL`.

- If the attribute is an internal LOB, then only the LOB locator from the source object is copied. A copy of the LOB data is not made until `OCIObjectFlush()` is called. Before the target object is flushed, both the source and the target locators refer to the same LOB value.

The target or the containing instance of the target must be already have been created. This may be done with OCIObjectNew() or OCIObjectPin() depending on whether or not the target object already exists.

The `source` and `target` instances must be of the same type. If the source and target are located in a different databases, then the same type must exist in both databases.

Related Functions

OCIObjectPin()

## OCIObjectGetAttr()

Purpose

Retrieves an object attribute.

Syntax

    sword OCIObjectGetAttr ( OCIEnv             *env,
                             OCIError           *err,
                             dvoid              *instance,
                             dvoid              *null_struct,
                             struct OCIType     *tdo,
                             CONST OraText      **names,
                             CONST ub4          *lengths,
                             CONST ub4          name_count,
                             CONST ub4          *indexes,
                             CONST ub4          index_count,
                             OCIInd             *attr_null_status,
                             dvoid              **attr_null_struct,
                             dvoid              **attr_value,
                             struct OCIType     **attr_tdo );

Parameters

env (IN/OUT)

  The OCI environment handle initialized in object mode. See the descriptions of OCIEnvCreate() and OCIInitialize()for more information.

err (IN/OUT)

  The OCI error handle. If there is an error, it is recorded in `err` and this function returns `OCI_ERROR`. Obtain diagnostic information by calling `OCIErrorGet()`.

instance (IN)

  Pointer to an object.

null_struct (IN)

  The `NULL` structure of the object or array.

tdo (IN)

  Pointer to the TDO.

names (IN)

  Array of attribute names. This is used to specify the names of the attributes in the path expression.

lengths (IN)

  Array of lengths of attribute names, in bytes.

name_count (IN)

  Number of element in the array `names`.

indexes (IN) [optional]

  Not currently supported. Pass as `(ub4 *)0`.

index_count (IN) [optional]

  Not currently supported. Pass as `(ub4)0`.

attr_null_status (OUT)

  The `NULL` status of the attribute if the type of attribute is primitive.

attr_null_struct (OUT)

  The `NULL` structure of an object or collection attribute.

attr_value (OUT)

  Pointer to the attribute value.

attr_tdo (OUT)

  Pointer to the TDO of the attribute.

Comments

This function gets a value from an object or from an array. If the parameter `instance` points to an object, then the path expression specifies the location of the attribute in the object. It is assumed that the object is pinned and that the value returned is valid until the object is unpinned.

Related Functions

OCIObjectSetAttr()

## OCIObjectGetInd()

Purpose

Gets the `NULL` indicator structure of a standalone instance.

Syntax

    sword OCIObjectGetInd ( OCIEnv        *env,
                            OCIError      *err,
                            dvoid         *instance,
                            dvoid         **null_struct );

Parameters

env (IN/OUT)

  The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() for more information.

err (IN/OUT)

  The OCI error handle. If there is an error, it is recorded in `err` and this function returns `OCI_ERROR`. Obtain diagnostic information by calling `OCIErrorGet()`.

instance (IN)

  A pointer to the instance whose `NULL` structure is being retrieved. The instance must be standalone. If `instance` is an object, it must already be pinned.

null_struct (OUT)

  The `NULL` indicator structure for the instance.

See Also: "NULL Indicator Structure" for a discussion of the NULL indicator structure and examples of its use.

Comments

None.

Related Functions

OCIObjectPin()

## OCIObjectGetObjectRef()

Purpose

Returns a reference to a given persistent object.

Syntax

    sword OCIObjectGetObjectRef ( OCIEnv        *env,
                                  OCIError      *err,
                                  dvoid         *object,
                                  OCIRef        *object_ref );

Parameters

env (IN/OUT)

  The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() for more information.

err (IN/OUT)

  The OCI error handle. If there is an error, it is recorded in `err` and this function returns `OCI_ERROR`. Obtain diagnostic information by calling `OCIErrorGet()`.

object (IN)

  Pointer to a persistent object. It must already be pinned.

object_ref (OUT)

  A reference to the object specified in `object`. The reference must already be allocated. This can be accomplished with `OCIObjectNew()`.

Comments

This function returns a reference to the given persistent object, given a pointer to the object. Passing a value (rather than an object) to this function causes an error.

See Also: For more information about object meta-attributes, see "Object Meta-Attributes".

Related Functions

OCIObjectPin()

## OCIObjectGetTypeRef()

Purpose

Returns a reference to the type descriptor object (TDO) of a standalone instance.

Syntax

    sword OCIObjectGetTypeRef ( OCIEnv        *env,
                                OCIError      *err,
                                dvoid         *instance,
                                OCIRef        *type_ref );

Parameters

env (IN/OUT)

  The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() for more information.

err (IN/OUT)

  The OCI error handle. If there is an error, it is recorded in `err` and this function returns `OCI_ERROR`. Obtain diagnostic information by calling `OCIErrorGet()`.

instance (IN)

  A pointer to the standalone instance. It must be standalone, and if it is an object, it must already be pinned.

type_ref (OUT)

  A reference to the type of the object. The reference must already be allocate. This can be accomplished with `OCIObjectNew()`.

Comments

None.

Related Functions

OCIObjectPin()

## OCIObjectLock()

Purpose

Locks a persistent object at the server.

Syntax

    sword OCIObjectLock ( OCIEnv        *env,
                          OCIError      *err,
                          dvoid         *object );

Parameters

env (IN/OUT)

  The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() for more information.

err (IN/OUT)

  The OCI error handle. If there is an error, it is recorded in `err` and this function returns `OCI_ERROR`. Obtain diagnostic information by calling `OCIErrorGet()`.

object (IN)

  A pointer to the persistent object being locked. It must already be pinned.

Comments

This function will return an error for transient objects and values. It also returns an error if the object does not exist.

See Also: For more information about object locking, see "Locking Objects For Update".

Related Functions

OCIObjectPin(), OCIObjectIsLocked(), OCIObjectGetProperty(), OCIObjectLockNoWait()

## OCIObjectLockNoWait()

Purpose

Locks a persistent object at the server but does not wait for the lock. and returns an error if the lock is unavailable.

Syntax

    sword OCIObjectLockNoWait ( OCIEnv        *env,
                                OCIError      *err,
                                dvoid         *object );

Parameters

env (IN/OUT)

  The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() for more information.

err (IN/OUT)

  The OCI error handle. If there is an error, it is recorded in `err` and this function returns `OCI_ERROR`. Obtain diagnostic information by calling `OCIErrorGet()`.

object (IN)

  A pointer to the persistent object being locked. It must already be pinned.

Comments

This function locks a persistent object at the server. However, unlike `OCIObjectLock()`, this function does not wait if another user holds the lock on the desired object and an error is returned if the object is currently locked by another user. This function also returns an error for transient objects and values, or objects that do not exist.

The lock of an object is released at the end of a transaction.

See Also: For more information about object locking, see "Locking Objects For Update".

`OCIObjectLockNoWait()` returns the following values:

- `OCI_INVALID_HANDLE`, if the environment handle or error handle is `NULL`.

- `OCI_SUCCESS`, if the operation suceeds.

- `OCI_ERROR`, if the operation fails.

Related Functions

OCIObjectPin(), OCIObjectIsLocked(), OCIObjectGetProperty(), OCIObjectLock()

## OCIObjectNew()

Purpose

Creates a standalone instance

Syntax

    sword OCIObjectNew ( OCIEnv            *env,
                         OCIError          *err,
                         CONST OCISvcCtx   *svc,
                         OCITypeCode       typecode,
                         OCIType           *tdo,
                         dvoid             *table,
                         OCIDuration       duration,
                         boolean           value,
                         dvoid             **instance );

Parameters

env (IN/OUT)

  The OCI environment handle initialized in object mode with Unicode setting. See the description of OCIEnvCreate() and OCIInitialize() for more information.

err (IN/OUT)

  The OCI error handle. If there is an error, it is recorded in `err` and this function returns `OCI_ERROR`. Obtain diagnostic information by calling `OCIErrorGet()`.

svc (IN) [optional]

  OCI service handle. It must be given if the program wants to associate the duration of an instance with an OCI service (for example, free a string when the transaction is committed). This parameter is ignored if the TDO is given.

typecode (IN)

  The typecode of the type of the instance.

  See Also: "Typecodes"

tdo (IN) [optional]

  Pointer to the type descriptor object. The TDO describes the type of the instance that is to be created. Refer to `OCITypeByName()` for obtaining a TDO. The TDO is required for creating a named type, such as an object or a collection.

table (IN) [optional]

  Pointer to a table object which specifies a table in the server. `This` parameter can be set to `NULL` if no table is given. See the following description to find out how the table object and the TDO are used together to determine the kind of instances (persistent, transient, value) to be created. Also see `OCIObjectPinTable()` for retrieving a table object.

duration (IN)

  This is an overloaded parameter. The use of this parameter is based on the kind of the instance that is to be created.

- Persistent object. This parameter specifies the pin duration.

- Transient object. This parameter specifies the allocation duration and pin duration.

- Value. This parameter specifies the allocation duration.

value (IN)

  Specifies whether the created object is a value. If `TRUE`, then a value is created. Otherwise, a referenceable object is created. If the instance is not an object, then this parameter is ignored.

instance (OUT)

  Address of the newly created instance. The instance can be a character string in Unicode if the environment handle has the appropriate setting and the object is OCIString. In this case, the instance will have a flag to indicate its Unicode setting.

Comments

This function creates a new instance of the type specified by the typecode or the TDO. It can create an OCIString object with a Unicode buffer if the typecode indicates the object to be created is OCIString.

See Also: "Typecodes"

Based on the parameters `typecode` (or `tdo`), `value` and `table`, different instances are created:

Table 17-10 Instances Created

Type Created | Not NULL | NULL
--- | --- | ---
object type (value=`TRUE`) | value | value
object type (value=`FALSE`) | persistent object | transient object
built-in type | value | value
collection type | value | value

This function allocates the top-level memory chunk of an instance. The attributes in the top-level memory are initialized which means that an attribute of `VARCHAR2` is initialized to a `OCIString` of 0 length. If the instance is an object, the object is marked existed but is atomically `NULL`.

See Also: For information about creating new objects based on object views or user-created OIDs, see "Creating Objects Based on Object Views or User-Defined OIDs".

For Persistent Objects

  The object is marked dirty and existed. The allocation duration for the object is session. The object is pinned and the pin duration is specified by the given parameter `duration`. Creating a persistent object does not cause any entries to be made into a database table until the object is flushed to the server.

For Transient Objects

  The object is pinned. The allocation duration and the pin duration are specified by the given parameter `duration`.

For Values

  The allocation duration is specified by the given parameter `duration`.

Attribute Values of New Objects

By default, all attributes of a newly created objects have `NULL` values. After initializing attribute data, the user must change the corresponding `NULL` status of each attribute to non-`NULL`.

It is possible to have attributes set to non-`NULL` values when an object is created. This is accomplished by setting the `OCI_ATTR_OBJECT_NEWNOTNULL` attribute of the environment handle to `TRUE` using `OCIAttrSet()`. This mode can later be turned off by setting the attribute to `FALSE`. If `OCI_ATTR_OBJECT_NEWNOTNULL` is set to `TRUE`, then `OCIObjectNew()` creates a non-`NULL` object.

See Also: "Attribute Values of New Objects"

Objects with LOB Attributes

If the object contains an internal LOB attribute, the LOB is set to empty. The object must be marked as dirty and flushed (in order to insert the object into the table) and repinned before the user can start writing data into the LOB. When pinning the object after creating it, you must use the `OCI_PIN_LATEST` pin option in order to retrieve the newly updated LOB locator from the server.

If the object contains an external LOB attribute (FILE), the FILE locator is allocated but not initialized. The user must call `OCILobFileSetName()` to initialize the FILE attribute before flushing the object to the database. It is an error to `INSERT` or `UPDATE` a FILE without first indicating a directory object and filename. Once the filename is set, the user can start reading from the FILE.

Note: Oracle now supports only binary FILEs (`BFILEs`).

Related Functions

OCIObjectPinTable(), OCIObjectFree()

## OCIObjectSetAttr()

Purpose

Set an object attribute.

Syntax

    sword OCIObjectSetAttr ( OCIEnv              *env,
                             OCIError            *err,
                             dvoid               *instance,
                             dvoid               *null_struct,
                             struct OCIType      *tdo,
                             CONST OraText       **names,
                             CONST ub4           *lengths,
                             CONST ub4           name_count,
                             CONST ub4           *indexes,
                             CONST ub4           index_count,
                             CONST OCIInd        null_status,
                             CONST dvoid         *attr_null_struct,
                             CONST dvoid         *attr_value );

Parameters

env (IN/OUT)

  The OCI environment handle initialized in object mode. See the description of OCIEnvCreate() and OCIInitialize() for more information.

err (IN/OUT)

  The OCI error handle. If there is an error, it is recorded in `err` and this function returns `OCI_ERROR`. Obtain diagnostic information by calling `OCIErrorGet()`.

instance (IN)

  Pointer to an object instance.

null_struct (IN)

  The `NULL` structure of the object instance or array.

tdo (IN)

  Pointer to the TDO.

names (IN)

  Array of attribute names. This is used to specify the names of the attributes in the path expression.

lengths (IN)

  Array of lengths of attribute names, in bytes.

name_count (IN)

  Number of element in the array `names`.

indexes (IN) [optional]

  Not currently supported. Pass as `(ub4 *)0`.

index_count (IN) [optional]

  Not currently supported. Pass as `(ub4)0`.

attr_null_status (IN)

  The `NULL` status of the attribute if the type of attribute is primitive.

attr_null_struct (IN)

  The `NULL` structure of an object or collection attribute.

attr_value (IN)

  Pointer to the attribute value.

Comments

This function sets the attribute of the given object with the given value. The position of the attribute is specified as a path expression which is an array of names and an array of indexes.

Example

For the path expression stanford.cs.stu[5].addr, the arrays will look like:

names = {"stanford", "cs", "stu", "addr"}

lengths = {8, 2, 3, 4}

indexes = {5}

Related Functions

OCIObjectGetAttr()